The tabbable npm package is used to identify DOM elements that are tabbable or focusable. This is useful for accessibility concerns, such as when creating keyboard navigation or managing focus within modal dialogs, dropdowns, and custom widgets. It helps ensure that keyboard users can navigate through all interactive elements on the page in a logical order.
Finding all tabbable elements
This feature allows you to get a list of all elements that are tabbable (can be focused using the Tab key) within a specified DOM node.
var tabbable = require('tabbable');
var tabbableElements = tabbable(document);
console.log(tabbableElements);Finding all focusable elements
This feature provides a list of all elements that are focusable, including those that are not tabbable but can still receive focus, such as elements with a tabindex='-1'. The option `{ includeContainer: true }` includes the container itself if it is focusable.
var tabbable = require('tabbable');
var focusableElements = tabbable(document, { includeContainer: true });
console.log(focusableElements);The focus-trap package is designed to trap focus within a DOM element, preventing the user from tabbing out of it. This is particularly useful for modal dialogs. It is similar to tabbable in that it deals with focus management, but it provides a higher-level API specifically for creating a focus trap rather than just identifying focusable elements.
ally.js is a JavaScript library that simplifies certain accessibility features, including focus management. It provides a broader range of accessibility utilities compared to tabbable, including the ability to find and manipulate focusable elements, but also extends to other areas such as accessible hiding of elements and maintaining disabled state across shadow DOM boundaries.
Small utility that returns an array of all* tabbable DOM nodes within a containing node.
*all has some necessary caveats, which you'll learn about by reading below.
The following are considered tabbable:
<button> elements<input> elements<select> elements<textarea> elements<a> elements with an href attribute<audio> and <video> elements with controls attributes<summary> element directly under a <details> element<details> element without a <summary> element[contenteditable] attributetabindex attributeAny of the above will not be considered tabbable, though, if any of the following are also true about it:
tabindex attributedisabled attributedisplay: none (*see "Display check" below to modify this behavior)visibility: hidden style<details> element (with the exception of the first <summary> element)<input type="radio"> element and a different radio in its group is checked<fieldset>If you think a node should be included in your array of tabbables but it's not, all you need to do is add tabindex="0" to deliberately include it. (Or if it is in your array but you don't want it, you can add tabindex="-1" to deliberately exclude it.) This will also result in more consistent cross-browser behavior. For information about why your special node might not be included, see "More details", below.
As old and as broad as reasonably possible, excluding browsers that are out of support or have nearly no user base.
Focused on desktop browsers, particularly Chrome, Edge, FireFox, Safari, and Opera.
Tabbable is not officially tested on any mobile browsers or devices.
⚠️ Microsoft no longer supports any version of IE, so IE is no longer supported by this library.
💬 Keep in mind that performance optimization and old browser support are often at odds, so tabbable may not always be able to use the most optimal (typically modern) APIs in all cases.
npm install tabbable
💬 Some very old browsers may need a polyfill for the CSS.escape API for tabbable to work properly with radio buttons that have
nameattributes containing special characters.
import { tabbable } from 'tabbable';
tabbable(container, [options]);
container: Node (Required)options:
includeContainer: boolean (default: false)
true, container will be included in the returned tabbable node array, if container is tabbable.container is inert, none of its children (deep) will be considered tabbable.Returns an array of ordered tabbable nodes (i.e. in tab order) within the container.
Summary of ordering principles:
tabindex attributes (1 or higher), ordered by ascending tabindex and source order.tabindex and any element that by default receives focus (listed above) and does not have a positive tabindex set, in source order.import { isTabbable } from 'tabbable';
isTabbable(node, [options]);
node: Node (Required)options:
Returns a boolean indicating whether the provided node is considered tabbable.
💬 If the node has an inert ancestor, it will not be tabbable.
import { focusable } from 'tabbable';
focusable(container, [options]);
container: Node: Requiredoptions:
includeContainer: boolean (default: false)
true, container will be included in the returned focusable node array, if container is focusable.container is inert, none of its children (deep) will be considered focusable.Returns an array of focusable nodes within the container, in DOM order. This will not match the order in which tabbable() returns nodes.
import { isFocusable } from 'tabbable';
isFocusable(node, [options]);
node: Node (Required)options:
Returns a boolean indicating whether the provided node is considered focusable.
💬 All tabbable elements are focusable, but not all focusable elements are tabbable. For example, elements with
tabindex="-1"are focusable but not tabbable. Also note that if the node has aninert ancestor, it will not be focusable.
import { getTabIndex } from 'tabbable';
getTabIndex(node);
node: Element (Required)Returns a negative, 0, or positive number that expresses the node's tab index in the DOM, with exceptions made where there are browser inconsistencies related to <audio>, <video>, <details>, and elements with the contenteditable="true" attribute.
The specific exceptions may change over time. See the implementation for specific behavior.
These options apply to all APIs.
Type: full | legacy-full | non-zero-area | none . Default: full.
Configures how to check if an element is displayed.
To reliably check if an element is tabbable/focusable, Tabbable defaults to the most reliable option to keep consistent with browser behavior, however this comes at a cost since every node needs to be validated as displayed using Web APIs that cause layout reflow.
For this reason Tabbable offers the ability of an alternative way to check if an element is displayed (or completely opt out of the check).
The displayCheck configuration accepts the following options:
full: (default) Most reliably resembling browser behavior, this option checks that an element is displayed, which requires it to be attached to the DOM, and for all of his ancestors to be displayed (notice this doesn't exclude visibility: hidden or elements with zero size). This option will cause layout reflow, however. If that is a concern, consider the none option.
tabbable() or focusable(), or the node given to isTabbable() or isFocusable(), is not attached to the window's main document, the node will be considered hidden and neither tabbable nor focusable. This behavior is new as of v6.0.0.legacy-full option.legacy-full: Same as full but restores the legacy behavior of treating detached nodes as visible. This means that if a node is detached, it's then treated as though the display check was set to none (see below for details).
full option) as long and smooth as reasonably possible.v6.0.0 release), and you may never have encountered an issue if the nodes with which you used tabbable were always displayed anyway (i.e. the none mode assumption was coincidentally correct).non-zero-area: This option checks display under the assumption that elements that are not displayed have zero area (width AND height equals zero). While not keeping true to browser behavior, this option may enhance accessibility, as zero-size elements with focusable content are considered a strong accessibility anti-pattern.
full option, this option also causes layout reflow, and should have basically the same performance. Consider the none option if reflow is a concern.full option, there is a nuance in behavior depending on whether tabbable APIs are executed on attached vs detached nodes using this mode: Attached nodes that are actually displayed will be deemed visible. Detached nodes, even though displayed will always be deemed hidden because detached nodes always have a zero area as the browser does not calculate is dimensions.none: This completely opts out of the display check. This option is not recommended, as it might return elements that are not displayed, and as such not tabbable/focusable and can break accessibility. Make sure you know which elements in your DOM are not displayed and can filter them out yourself before using this option.⚠️ Testing in JSDom (e.g. with Jest): See notes about testing in JSDom.
By default, tabbable overlooks (i.e. does not consider) all elements contained in shadow DOMs (whether open or closed). This has been the behavior since the beginning.
Setting this option to a truthy value enables Shadow DOM support, which means tabbable will consider elements inside web components as candidates, both open (automatically) and closed (provided this function returns the shadow root).
Type: boolean | (node: FocusableElement) => ShadowRoot | boolean | undefined
boolean:
true simply enables shadow DOM support for any open shadow roots, but never presumes there is an undisclosed shadow. This is the equivalent of setting getShadowRoot: () => falsefalse (default) disables shadow DOM support in so far as calculated tab order and closed shadow roots are concerned. If a child of a shadow (open or closed) is given to isTabbable() or isFocusable(), the shadow DOM is still considered for visibility and display checks.function:
node will be a descendent of the container given to tabbable(), isTabbable(), focusable(), or isFocusable().ShadowRoot if available, true indicating a ShadowRoot is attached but not available (i.e. "undisclosed"), or a falsy value indicating there is no shadow attached to the node.If set to a function, and if it returns
true, Tabbable assumes a closedShadowRootis attached and will treat the node as a scope, iterating its children for additional tabbable/focusable candidates as though it was looking inside the shadow, but not. This will get tabbing order closer to -- but not necessarily the same as -- browser order.Returning
truefrom a function will also inform how the node's visibility check is done, causing tabbable to use the non-zero-area Display Check when determining if it's visible, and so tabbable/focusable.
<object> and <iframe> — so this means some elements that you can tab to in some browsers will be left out of the results. (To learn more about this inconsistency, see this amazing table). To provide better consistency across browsers and ensure the elements you want in your tabbables list show up there, try adding tabindex="0" to edge-case elements that Tabbable ignores.<iframe>, <embed>, <object>, <summary>, and <svg> nodes is inconsistent across browsers, so if you need an accurate read on one of these elements you should try giving it a tabindex. (You'll also need to pay attention to the focusable attribute on SVGs in Edge.) But you also might not be able to get an accurate read — so you should avoid relying on it.checked one in each group (and that is what you should usually do anyway). If there is no checked radio in the radio group, all of the radios will be considered tabbable. (Some browsers do this, otherwise don't — there's not consistency.)querySelectorAll?", you may be on to something ... but, as with most "just" statements, you're probably not. For example, a simple querySelectorAll approach will not figure out whether an element is hidden, and therefore not actually tabbable. (That said, if you do think Tabbable can be simplified or otherwise improved, I'd love to hear your idea.):tabbable selector ignores elements with height and width of 0. I'm not sure why — because I've found that I can still tab to those elements. So I kept them in. Only elements hidden with display: none or visibility: hidden are left out. See "Display check" below for other options.<a> elements by default: you have to change a setting to get the standard behavior. Tabbable does not know whether you've changed that setting or not, so it will include <a> elements in its list.⚠️ JSDom is not officially supported. Your mileage may vary, and tests may break from one release to the next (even a patch or minor release).
This topic is just here to help with what we know may affect your tests.
Tabbable uses some DOM APIs such as Element.getClientRects() in order to determine node visibility, which helps in deciding whether a node is tabbable, focusable, or neither.
When using test engines such as Jest that use JSDom under the hood in order to run tests in Node.js (as opposed to using an automated browser testing tool like Cypress, Playwright, or Nightwatch where a full DOM is available), it is highly recommended (if not essential) to set the displayCheck option to none when calling any of the APIs in this library that accept it.
Using any other displayCheck setting will likely lead to failed tests due to nodes expected to be tabbable/focusable being determined to be the opposite because JSDom doesn't fully support some of the DOM APIs being used (even old ones that have been around for a long time).
You can globally overwrite the diplayCheck property by including this file in your __mocks__ folder:
// __mocks__/tabbable.js
const lib = jest.requireActual('tabbable');
const tabbable = {
...lib,
tabbable: (node, options) => lib.tabbable(node, { ...options, displayCheck: 'none' }),
focusable: (node, options) => lib.focusable(node, { ...options, displayCheck: 'none' }),
isFocusable: (node, options) => lib.isFocusable(node, { ...options, displayCheck: 'none' }),
isTabbable: (node, options) => lib.isTabbable(node, { ...options, displayCheck: 'none' }),
};
module.exports = tabbable;
Feedback and contributions more than welcome!
See CONTRIBUTING.
In alphabetical order:
6.2.0
getTabIndex() API which enables Focus-trap to determine tab indexes in the same way as Tabbable when necessary (see focus-trap#974).FAQs
Returns an array of all tabbable DOM nodes within a containing node.
The npm package tabbable receives a total of 2,927,183 weekly downloads. As such, tabbable popularity was classified as popular.
We found that tabbable demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.